Control and Monitor Tor
Donate
Using a Tor Controller with Whonix. Onion Circuits. Nyx. View or change your Tor circuits. Monitor Tor and inspect logs.
Introduction[edit]
nyx is the primary Tor Controller option that comes pre-installed in Whonix.
Note: Vidalia has been deprecated and is no longer packaged in Debian.
Nyx[edit]
The nyx
Tor controller is a later version of the arm package, so the functionality and appearance are very similar. The Tor Project nyx homepage states: "Nyx is a command-line monitor for Tor. With this you can get detailed real-time information about your relay such as bandwidth usage, connections, logs, and much more."
Nyx Usage[edit]
Nyx is recommended and is already pre-installed in Whonix-Gateway™. [1]
If you are using Qubes-Whonix™, complete the following steps.
Qubes App Launcher (blue/grey "Q") → Whonix-Gateway™ ProxyVM (commonly named sys-whonix) → Nyx - Status Monitor for Tor
If you are using a graphical Whonix-Gateway, complete the following steps.
Start Menu → Applications → System → Nyx - Status Monitor for Tor
If you are using a terminal Whonix-Gateway, type.
nyx
To receive a new circuit, press:
n
To exit nyx, press:
q q
Nyx FAQ[edit]
| Message / Question | Response |
|---|---|
| arm vs nyx? | The software was previously called arm, but the new name is nyx. [2]
|
| Should any of the following nyx messages concern me? | No; see below for reasons why. See also: Indicators of Compromise and Support Request Policy (rationale). |
| Am I compromised? Does nyx report leaks? | Nyx is conceptually not a tool to discover serious issues such as a possible compromise or leaks. [3] |
Nyx sometimes shows my public IP address and other times the internal 10.0.2.15 and 127.0.0.1 IPs. Is it normal or dangerous? [4]
|
This is a normal nyx feature. Whonix uses a Tor control port filter proxy (onion-grater) that prevents abuse of the ControlPort, including blocking dangerous commands like GETINFO address. When the real IP address appears, it is only local and nobody else can see it.
|
| Tor is preventing system utilities like netstat and lsof from working. This means that nyx can't provide you with connection information. You can change this by adding 'DisableDebuggerAttachment 0' to your torrc and restarting tor. For more information see... https://gitlab.torproject.org/legacy/trac/-/issues/3313
|
If you want to learn about the technical details, read https://gitlab.torproject.org/legacy/trac/-/issues/3313.
|
| DisableDebuggerAttachment even when running as root. | This bug in nyx has been resolved.
|
| man page (GENERAL OPTIONS and COMMAND-LINE OPTIONS) | This bug in nyx has been resolved.
|
| [WARN] Socks version 71 not recognized. (Tor is not an http proxy.) |
This is caused by the systemcheck |
| [WARN] Socks version 71 not recognized. (This port is not an HTTP proxy; did you want to use HTTPTunnelPort?) | This occurs for similar reasons to the entry above. |
| [WARN] Rejecting request for anonymous connection to private address [scrubbed] on a TransPort or NATDPort. Possible loop in your NAT rules? | This happens for example if you run "curl 192.168.0.15". The reason is when you type "curl" in Whonix, by default you are not directly using curl, but a uwt-wrapped (stream-isolated) curl instead. It does not try to directly connect to 192.168.0.15, but rather to connect to 192.168.0.15 through Tor, leading to this Tor message. It really means an operation was attempted that will not work in that way. In this instance, deactivate the curl stream isolation wrapper or use the non-wrapped version - see Stream Isolation. |
| [NOTICE] You configured a non-loopback address '10.152.152.10:9179' for SocksPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. [1 duplicate hidden] (Or another port number or DnsPort or TransPort.) | Tor really listens on that IP/port. It is Whonix-Gateway network interface and is only available to Whonix-Workstation™. This restriction is enforced by an internal network with Whonix-Workstation™(s) and because Whonix-Gateway is firewalled; see /usr/bin/whonix_firewall or the Whonix source code for more information. |
| [NOTICE] New control connection opened. [2 duplicates hidden] (Or more duplicates.) | This is caused by systemcheck's Tor Bootstrap Status Test, which uses Tor's ControlPort or CPFP.
|
| [NOTICE][NYX_WARN] The torrc differ from what tor's using. You can issue a sighup to reload the torrc values by pressing x. Configuration value is missing from the torrc: RunAsDaemon | Nyx usability bug. [6] [7] |
| "192.168.0.1 UNKNOWN 1 / Guard" in circuit information | This indicates that you are connecting to the Tor network with a Tor Bridge.
If you are directly connecting to the public Tor network without a Tor Bridge, the real IP and Nickname of the Guard should be visible instead. [8] |
Nyx Autostart[edit]
Optional.
1. Platform specific notice:
- Non-Qubes-Whonix: No special notice.
- Qubes-Whonix: Inside Template.
2. Symlink start menu entry to autostart.
sudo ln -s /usr/share/applications/gateway-nyx.desktop /etc/xdg/autostart/gateway-nyx.desktop
3. Done.
Nyx should now autostart after the next reboot.
Onion Circuits[edit]
Onion Circuits is a GTK+ application to display Tor circuits and streams. It allows the user to inspect the circuits the locally running Tor daemon has built, along with some metadata for each node.
Onion Circuits is installed by default, but is not a full Tor controller; only Tor circuits are shown. It can be launched from the start menu.
New Identity and Tor Circuits[edit]
The behavior of "New Identity" in the context of Tor Browser and nyx is often misunderstood. First of all, there are various ways to issue a "New Identity" (this list is not exhaustive):
In all cases, the "New Identity" function sends the protocol command SIGNAL newnym to Tor's ControlPort.
Tor Browser's new identity function additionally clears the browser state, closes tabs and obtains a fresh Tor circuit for future requests. [10]
Other Tor controllers such as nyx run only SIGNAL newnym.
Warning: The New Identity feature will likely create a new circuit with a different Tor exit relay and IP Address, but this is not guaranteed.
The impact of "signal newnym" on Tor circuit lifetimes is often misunderstood. "signal newnym" uses a fresh circuit for new connections. Sometimes Tor only replaces the middle relay while using the same Tor exit relay. This is by design and the Tor default. Further, "signal newnym" does not interfere with long-lived connections like an file downloads, website downloads, SSH or IRC connections.
Interested readers can verify the effect of "signal newnym" as follows:
- Open https://check.torproject.org in Tor Browser.
- Issue "signal newnym" using nyx.
- Reload https://check.torproject.org.
- In some cases it will still show the same IP address, probably because the browser did not close the connection to https://check.torproject.org in the first place.
Now repeat this experiment with a small modification which should result in a new Tor exit IP address:
- Open https://check.torproject.org in Tor Browser.
- Issue "signal newnym" using nyx.
- Close Tor Browser, then restart it.
- Open https://check.torproject.org again and a new Tor exit relay IP address is (likely) visible.
New identity is not an IP selection or cycling feature. It is a circuit changer. Not an IP changer. Tor replaces your real external IP address with a Tor IP but it does not easily let users pick any specific IP. Tor chooses the IP. Whonix does not influence that. This is unspecific to Whonix.
Forcing an IP change might be possible. This is discouraged as per Tor Routing Algorithm. By changing Tor configuration, selection of specific IPs might be possible. This is unsupported and the user would need to edit the Tor configuration. Which settings specifically, the user would need to research as per Self Support First Policy, not by asking in Whonix forums.
tor-ctrl[edit]
tor-ctrl is installed by default.
For example, to get a new circuit, run.
tor-ctrl signal NEWNYM
The output should show:
250 OK
Repeat this command every time a new circuit is desired.
See also:
man tor-ctrl
Alternatives[edit]
Advanced users only.
Talking to the real Tor Controller[edit]
To talk to the real Tor Controller, you should run the commands on the Whonix-Gateway, as the Whonix-Workstation, the connection goes through the onion-grater controller proxy and some commands might be filtered.
On Whonix-Gateway. test is the example password being used. Feel free to use a different/stronger one.
tor --hash-password test
Will show something like this:
16:1CEAF6E6A08E0CF460AFD71772461C5F56BD9738FA8824B882FCA4A785
Open file /usr/local/etc/torrc.d/50_user.conf in a text editor of your choice with sudoedit.
If you are using Qubes-Whonix™, complete the following steps.
Qubes App Launcher (blue/grey "Q") → Whonix-Gateway™ ProxyVM (commonly named sys-whonix) → Tor User Config (Torrc)
If you are using a graphical Whonix-Gateway, complete the following steps.
Start Menu → Applications → Settings → /usr/local/etc/torrc.d/50_user.conf
If you are using a terminal-only Whonix-Gateway, complete the following steps. sudoedit /usr/local/etc/torrc.d/50_user.conf
HashedControlPassword 16:1CEAF6E6A08E0CF460AFD71772461C5F56BD9738FA8824B882FCA4A785
Reload Tor.
After changing Tor configuration, Tor must be reloaded for changes to take effect.
Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.
If you are using Qubes-Whonix™, complete the following steps.
Qubes App Launcher (blue/grey "Q") → Whonix-Gateway™ ProxyVM (commonly named 'sys-whonix') → Reload Tor
If you are using a graphical Whonix-Gateway, complete the following steps.
Start Menu → Applications → Settings → Reload Tor
If you are using a terminal-only Whonix-Gateway, click
HERE for instructions.
Complete the following steps.
Reload Tor.
sudo service tor@default reload
Check Tor's daemon status.
sudo service tor@default status
It should include a a message saying.
Active: active (running) since ...
In case of issues, try the following debugging steps.
Check Tor's config.
sudo -u debian-tor tor --verify-config
The output should be similar to the following.
Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf". Configuration was valid
sudo service tor reload
Connect to Tor's Controller:
sudo -n -u debian-tor socat - UNIX-CONNECT:/var/run/tor/control
Authenticate:
authenticate "test"
Should reply the following if successful:
250 OK
Test your commands. For example, start logging stream events:
setevents stream
Will do nothing after this, but when you start using Tor (i.e. by running Tor Browser, APT or so), it will show the stream events similar to the example below:
650 STREAM 211 NEW 0 pop.riseup.net:995 SOURCE_ADDR=10.152.152.11:47036 PURPOSE=USER ...
Whonix has a wrapper called tor-ctrl to communicate directly with tor's controller. By using it, you don't have to worry about authentication method, or which program to use to connect to the socket, or which program to use to convert the cookie to base32. As the intent of this section is to teach how to communicate without external programs, this is mentioned at last. If you wish to accomplish the same as above, you can do so with tor-ctrl -w setevents stream.
netcat[edit]
netcat is no longer required. tor-ctrl is recommended instead.
netcat provides an easy way to send Tor protocol commands to Tor's ControlPort form inside Whonix-Workstation. Actually for security reasons to onion-grater, the Tor Control Protocol Filter Proxy.
Inside Whonix-Workstation.
1. Install netcat.
sudo apt install netcat-openbsd
2. Connect to Tor's ControlPort. [11]
nc 127.0.0.1 9051
3. Example command to change the Tor circuit.
signal newnym
The output should be.
250 OK
tor-prompt[edit]
On Whonix-Gateway, run.
Example tor-prompt in non-interactive mode.
tor-prompt --no-color --run "getinfo consensus/valid-until"
Example tor-prompt in interactive mode.
On Whonix-Gateway, run.
tor-prompt
Will be greeted with the following or similar introduction message.
Welcome to Stem's interpreter prompt. This provides you with direct access to
Tor's control interface.
This acts like a standard python interpreter with a Tor connection available
via your 'controller' variable...
>>> controller.get_info('version')
'0.2.5.1-alpha-dev (git-245ecfff36c0cecc)'
You can also issue requests directly to Tor...
>>> GETINFO version
250-version=0.2.5.1-alpha-dev (git-245ecfff36c0cecc)
250 OK
For more information run '/help'.
>>>
Run any Tor control protocol command. For example GETINFO version. Replace GETINFO version with the actual command intended to run.
GETINFO version
Should show something similar to.
250-version=0.2.5.1-alpha-dev (git-245ecfff36c0cecc) 250 OK
Deprecated[edit]
Vidalia[edit]
Vidalia is no longer maintained.
Vidalia is recommended against because development has ceased, leading to it being removed from all Debian variants (stretch, sid etc.) as well as from Tor Browser Bundle v3.5 by The Tor Project. [12] [13] Vidalia had a number of limitations, such as an inability to fully control Tor -- it could not stop Tor which came with the Debian package because it is started as user "debian-tor". It also could not edit /usr/local/etc/torrc.d/50_user.conf [14] and did not understand obfuscated bridges. Since Vidalia has been deprecated and provides a pretty bad and confusing user experience, it is simply better to use nyx. [15]
See Also[edit]
Footnotes[edit]
- ↑ Since Vidalia is recommended against.
- ↑ https://tor.stackexchange.com/tags/nyx/info
- ↑
Nyx works on a different level -- it is a Tor Controller. Nyx talks to Tor using Tor's
ControlPortand is an interface to show what Tor thinks. Neither Tor nor nyx implement anything like virus detection, compromise detection, leak detection and so on. Nyx messages are generally interesting and useful, but there is rarely any cause for concern. For leak testing, see leak tests. - ↑ https://forums.whonix.org/t/strange-nyx-behavior/9514
- ↑ UWT_DEV_PASSTHROUGH=1 curl 10.152.152.10:9100
- ↑ https://gitlab.torproject.org/legacy/trac/-/issues/16459
- ↑ The issue was closed as 'not a bug' several years ago.
- ↑ https://forums.whonix.org/t/how-to-check-if-i-configured-bridges-correctly-and-the-bridges-are-working-properly/4371/5
- ↑ https://packages.debian.org/bookworm/onioncircuits
- ↑
https://blog.torproject.org/torbutton-141-released
- ↑
This works in Whonix-Workstation, because the anon-ws-disable-stacked-tor package has set up listening for connections on localhost and forwards them to Whonix-Gateway, where the onion-grater (Control Port Filter Proxy) is listening.
- ↑ https://tor.stackexchange.com/questions/1075/what-happened-to-vidalia
- ↑ As noted by Tor developer Roger Dingledine:
Cammy is right -- we've removed the bridge/relay/exit bundles from the download page too, since Vidalia has been unmaintained for years and pointing people to unmaintained software is dangerous. I'd love to have enough developers to do everything at once, but we don't.
- ↑ It is unclear whether control commands such as New Identity were correctly processed either.
- ↑ Unless the reader is interested in Vidalia's nice network map.
The most watertight privacy operating system in the world.
At
Whonix we value freedom and trust, supporting Open Source and Freedom Software
2012-
2024 ENCRYPTED SUPPORT LP
We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!